[Day03] GraphQL 魔法起源：為何它比 RESTful API 更適合你？

2023 iThome 鐵人賽

DAY 3

Vue.js

Vue & GraphQL 探險之旅：30天，從新手村到魔王之巔系列第 3 篇

15th鐵人賽

Miyuki

2023-09-18 22:34:42

438 瀏覽

分享至

身為現代的 Web 應用開發者，串接 API 已成為日常不可或缺的技能。

目前，最受歡迎的兩種選擇是 GraphQL 和 RESTful API，它們擁有著截然不同的 API 設計哲學和標準。

在本文中，我們會探討這兩者的主要差異、GraphQL 的獨特優勢，以及什麼情境適合優先考慮使用 GraphQL。

RESTful API vs GraphQL

RESTful API

RESTful (Representational State Transfer) 是一種網路架構原則。

使用標準的 HTTP 方法來進行資料的 CRUD 操作。
- 建立 (Create): POST
- 讀取 (Read): GET
- 更新 (Update): PUT 或 PATCH
  - 註：PUT 通常用於更新資源的完整內容，而 PATCH 則用於部分更新。
- 刪除 (Delete): DELETE
其誕生之初，RESTful 就被設計為無狀態、可緩存的。
具備良好的擴展性，適合處理多種資料類型。

RESTful API 以「資源」為核心概念

每個資源 (Resource) 或集合都對應一個特定的 URL，亦稱為端點（endpoint）。

對於 "My Blog All Posts" 頁面，API 提供者可能會提供以下的端點：

為了獲取這個頁面的資料，我們需要：

呼叫「讀取所有文章列表」API
Response

{
  "posts": [
    {
      "id": "1",
      "title": "First Post",
      "content": "Content of the first post.",
      "user_id": "1",
      "tags": ["Tutorial", "Introduction"],
      "date":"2023-01-01"
    },
    ...
  ]
}

再呼叫「讀取所有使用者列表」API，並根據文章中的 user_id 做 mapping。
Response

{
  "users": [
    {
      "id":1,
      "name":"Alice",
      "email":"alice@example.com"
    },
    ...
  ]
}

因為「文章」是一個資源，而「使用者」則是另一個資源。

GraphQL

GraphQL 是由 Facebook 在 2015 年開源的資料查詢語言。它不只是一種語言，同時也是與 API 交互的規範。專為 Web / Mobile 應用的開發者設計，讓他們可以從後端 API 精確地獲得所需資料。GraphQL 的誕生，主要是為了讓開發者有更靈活的查詢方式以及更高效的資料交換。

GraphQL 以「查詢」為核心概念

不同於 RESTful API 的多個端點，GraphQL 僅有一個端點（通常是 /graphql）。

客戶端發送「查詢」(Query) 來明確指定所需的資料結構，確保只獲取真正需要的資料。加上 GraphQL 的強型別性質，它可以在伺服器端進行查詢檢驗，從而確保只執行合法的查詢。

"My Blog All Posts" 頁面要獲取所需資料，使用 GraphQL 只需一個 POST 請求：

該請求的 Response 如下：

{
   "data":{
      "allPosts":[
         {
            "id":"1",
            "title":"First Post",
            "content":"Content of the first post.",
            "User":{
               "id": 1,
               "name":"Alice",
               "__typename":"User"
            },
            "__typename":"Post"
         },
         ...
      ]
   }
}

可以觀察到，在一個 Response 內就取得了 Posts & User 的資料

GraphQL 的獨特優勢

從前述的範例中，我們可以清晰地觀察到 GraphQL 的以下主要優勢：

更靈活的查詢方式 - 資料結構彈性與客製化
RESTful API 回應的結構通常是固定的，而 GraphQL 允許客戶端自訂所需的資料結構，增加開發彈性。
這解決了一些 RESTful API 的缺陷：
- 解決資料過多或過少的問題
  - RESTful API：由於回應的資料結構是由伺服器端決定的，可能會出現取得過多不必要資料（over-fetching）或資料不足（under-fetching）的情況。例如：前述的例子中，「讀取所有文章列表」的 RESTful API 回傳中的 tags, date 在目前頁面根本沒有用到。
  - GraphQL：客戶端可指定所需的數據結構，精確取得真正需要的資料。例如：當頁面改成只需要顯示標題時，將 Query 移除 content 就可以精簡資料。
- 版本控制的優勢
  - RESTful API：API 更新或新增功能可能需引入新版本端點，例如 /v2/users。
  - GraphQL：允許在現有架構中輕鬆添加或棄用字段，使版本控制更直觀、彈性。例如：新增自訂頭像功能後，只需在 User 字段加入 avatar 即可取得使用者頭像。
更高效的資料交換
- RESTful API：若需獲取多個資源的資訊，可能需要進行多次的 HTTP 請求。
- GraphQL：客戶端一次指定所有所需資訊，僅透過單一請求取得資料。
GraphQL 其他額外優點（後續章節將詳細介紹）：
- 更精確的錯誤處理
  比起 RESTful API 常使用 HTTP 狀態碼來表示請求的狀態或錯誤，GraphQL 總是回傳 200 HTTP 狀態碼，但在回應的內容中提供具體的錯誤訊息，允許更詳細的錯誤處理。
```
{
 "errors": [
   {
     "message": "Field 'username' is not defined in the schema.",
     "locations": [
       {
         "line": 2,
         "column": 3
       }
     ],
     "path": [
       "user",
       "username"
     ],
     "extensions": {
       "code": "GRAPHQL_VALIDATION_FAILED"
     }
   }
 ],
 "data": null
}
```
- 強大的類型系統
  GraphQL 具備詳盡的類型系統，讓開發者清晰知道 API 的能力，並確保資料的結構正確性。
- 友善的開發者工具
  GraphQL 提供了如 GraphQL Playground、Apollo Client Devtools 等為 GraphQL 設計的專用工具，幫助開發者更有效率地測試、偵錯和優化查詢。

　
看到這裡，是不是躍躍欲試了呢？

什麼情境適合優先考慮使用 GraphQL

實際上 RESTful API 與 GraphQL 各有優勢，但當開發者面臨以下情境時，優先考慮使用 GraphQL 可能是一個良好的選擇：

跨平台的客戶端應用
- 情境：若你正在為產品開發多個客戶端版本，包括網頁版、移動端和桌面應用。雖然主要功能相似，但每個客戶端根據其特性和使用情境可能會有不同的資料展示需求。
- 優勢：使用 GraphQL，每個客戶端都可以根據自己的需求指定所需的資料結構。例如，移動端可能只需要部分資訊，而網頁版則需要較詳細的內容。這樣既避免了不必要的資料請求，又確保了每個客戶端都能獲得其所需的資料。
快速成長的專案
- 情境：新創公司在初創時期，產品功能可能還相對簡單。但隨著市場反應和用戶需求，它可能迅速地加入多種新功能，如用戶互動、個性化推薦等。在這樣的發展過程中，前端的需求會頻繁地改變和調整。
- 優勢：對於快速發展和不斷變化的專案環境，GraphQL 提供了極大的彈性，允許在現有的架構中靈活地增加或移除字段。這意味著前端團隊可以迅速適應新功能的資料需求，無需等待後端的頻繁更新，從而提高整體的開發效率。
大型企業的內部系統集成
- 情境：在大型企業中，有時會面臨將多個舊有系統整合至一個統一前端界面的挑戰。這些系統可能涵蓋了人力資源、財務到項目管理的各種工具，每一套都帶有其獨特的資料格式和 API。
- 優勢：使用 GraphQL，企業能夠打造一個統一的API層，使前端應用能夠輕易地從多種來源取得必要的資料。這種做法減少了前端工程師在面對多種 API 和資料格式時的複雜性，進而極大地簡化了整合工作的難度。